Staff Portal Implementation

**Referenced Files in This Document** - [src/staff.njk](file://src/staff.njk) - [src/staff-knowledge.njk](file://src/staff-knowledge.njk) - [src/staff-knowledge-graph.njk](file://src/staff-knowledge-graph.njk) - [src/staff-knowledge-graph-data.njk](file://src/staff-knowledge-graph-data.njk) - [src/staff-knowledge-graph.js](file://src/assets/js/modules/staff-knowledge-graph.js) - [src/staff-knowledge-list.js](file://src/assets/js/modules/staff-knowledge-list.js) - [src/staff-knowledge-toc.js](file://src/assets/js/modules/staff-knowledge-toc.js) - [src/_includes/layouts/staff-knowledge-article.njk](file://src/_includes/layouts/staff-knowledge-article.njk) - [src/assets/css/modules/45-staff-portal.css](file://src/assets/css/modules/45-staff-portal.css) - [src/assets/css/modules/47-staff-knowledge-scope.css](file://src/assets/css/modules/47-staff-knowledge-scope.css) - [src/admin/config.yml](file://src/admin/config.yml) - [src/admin/index.html](file://src/admin/index.html) - [worker.js](file://worker.js) - [package.json](file://package.json) - [src/content/knowledge/knowledge.11tydata.js](file://src/content/knowledge/knowledge.11tydata.js) - [src/content/knowledge/briefing-note-playbook.md](file://src/content/knowledge/briefing-note-playbook.md) - [src/content/knowledge/media-enquiry-protocol.md](file://src/content/knowledge/media-enquiry-protocol.md) - [src/content/knowledge/staff-onboarding.md](file://src/content/knowledge/staff-onboarding.md) - [src/_includes/layouts/knowledge.njk](file://src/_includes/layouts/knowledge.njk) - [src/_data/site.json](file://src/_data/site.json)

Update Summary

Changes Made

  • Enhanced knowledge base with three new staff-only articles: Briefing Note Playbook, Media Enquiry Protocol, and Staff Onboarding
  • Improved filtering system with enhanced JavaScript modules for better user experience
  • Updated knowledge graph visualization with improved D3.js modules and enhanced interactivity
  • Refined staff knowledge base styling with comprehensive theme support
  • Added comprehensive staff-only content management with audience segmentation

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Enhanced Knowledge Base Infrastructure
  7. Improved Filtering System
  8. Enhanced Knowledge Graph Visualization
  9. Staff-Only Content Management
  10. Dependency Analysis
  11. Performance Considerations
  12. Troubleshooting Guide
  13. Conclusion

Introduction

This document provides a comprehensive analysis of the enhanced Staff Portal Implementation for the Ace Strategies platform. The Staff Portal serves as an internal hub for Ace Strategies employees, offering centralized access to the Content Management System (CMS), the full knowledge base (including drafts and staff-only content), and technical platform documentation. The implementation has been significantly enhanced with new knowledge base infrastructure, improved filtering capabilities, and comprehensive staff-only content management.

The portal leverages a magic-link authentication system shared with the Invest Australia Alliance (IAA) members portal, ensuring secure access to internal resources while maintaining a seamless user experience. The enhanced implementation emphasizes accessibility, responsive design, efficient content discovery through advanced filtering and graph visualization capabilities, and robust staff-only content segregation.

Project Structure

The enhanced Staff Portal implementation spans several key areas within the repository:

  • Templates and Pages: Nunjucks templates for the Staff Portal, Knowledge Base, Knowledge Graph, and Platform Documentation
  • Enhanced Knowledge Base: New staff-only articles integrated with improved filtering and visualization
  • Styling: Comprehensive CSS modules supporting theme switching and responsive layouts
  • Administration: Sveltia CMS configuration and integration for content management
  • Authentication: Cloudflare Worker implementing magic-link authentication and session management
  • Content Management: Enhanced Eleventy data configuration for knowledge base articles and collections
  • Build and Deployment: NPM scripts for building, previewing, and deploying the platform
graph TB
subgraph "Enhanced Staff Portal Frontend"
SP["Staff Portal (/staff/)"]
KB["Knowledge Base (/staff/knowledge/)"]
KG["Knowledge Graph (/staff/knowledge/graph/)"]
PD["Platform Docs (/staff/platform-docs/)"]
end
subgraph "Enhanced Knowledge Base"
NEW1["Briefing Note Playbook"]
NEW2["Media Enquiry Protocol"]
NEW3["Staff Onboarding"]
FILTER["Advanced Filtering System"]
GRAPH["Enhanced Graph Visualization"]
end
subgraph "CMS Integration"
CMS["Sveltia CMS (/admin/)"]
CFG["Admin Config (config.yml)"]
end
subgraph "Authentication Layer"
WRK["Cloudflare Worker (worker.js)"]
AUTH["Magic Link Auth"]
SESS["Session Management"]
end
subgraph "Content Management"
ELE["Eleventy (knowledge.11tydata.js)"]
DATA["_data/site.json"]
LAYOUT["Staff Knowledge Layout"]
end
SP --> WRK
KB --> WRK
KB --> FILTER
KB --> GRAPH
KG --> WRK
KG --> GRAPH
PD --> WRK
CMS --> WRK
WRK --> AUTH
WRK --> SESS
WRK --> ELE
ELE --> LAYOUT
ELE --> DATA
CMS --> CFG
NEW1 --> KB
NEW2 --> KB
NEW3 --> KB

Diagram sources

  • [src/staff.njk:1-168](file://src/staff.njk#L1-L168)
  • [src/staff-knowledge.njk:1-192](file://src/staff-knowledge.njk#L1-L192)
  • [src/staff-knowledge-graph.njk:1-55](file://src/staff-knowledge-graph.njk#L1-L55)
  • [src/staff-knowledge-graph.js:1-217](file://src/assets/js/modules/staff-knowledge-graph.js#L1-L217)
  • [src/staff-knowledge-list.js:1-99](file://src/assets/js/modules/staff-knowledge-list.js#L1-L99)
  • [src/content/knowledge/briefing-note-playbook.md:1-97](file://src/content/knowledge/briefing-note-playbook.md#L1-L97)
  • [src/content/knowledge/media-enquiry-protocol.md:1-108](file://src/content/knowledge/media-enquiry-protocol.md#L1-L108)
  • [src/content/knowledge/staff-onboarding.md:1-109](file://src/content/knowledge/staff-onboarding.md#L1-L109)

Section sources

  • [src/staff.njk:1-168](file://src/staff.njk#L1-L168)
  • [src/staff-knowledge.njk:1-192](file://src/staff-knowledge.njk#L1-L192)
  • [src/staff-knowledge-graph.njk:1-55](file://src/staff-knowledge-graph.njk#L1-L55)
  • [src/staff-knowledge-graph.js:1-217](file://src/assets/js/modules/staff-knowledge-graph.js#L1-L217)
  • [src/staff-knowledge-list.js:1-99](file://src/assets/js/modules/staff-knowledge-list.js#L1-L99)

Core Components

The enhanced Staff Portal implementation consists of six primary components that work together to deliver a comprehensive internal experience:

Staff Portal Dashboard

The main dashboard serves as the central hub, providing quick access to all staff portal features. It displays real-time statistics, recent activity, and direct links to key functionalities including the CMS, knowledge base, and platform documentation.

Enhanced Knowledge Base Interface

A comprehensive knowledge management system that presents articles in an advanced searchable, filterable table format. The interface supports status-based filtering (draft, review, published, archived), category-based organization, and enhanced audience segmentation (staff-only vs. public). Now includes three new staff-only articles: Briefing Note Playbook, Media Enquiry Protocol, and Staff Onboarding.

Advanced Knowledge Graph Visualization

An interactive force-directed graph that visualizes relationships between knowledge articles. Users can explore connections between documents, understand content dependencies, and navigate the knowledge ecosystem through enhanced visual clustering and categorization. The graph now supports improved tooltips, zoom controls, and theme-aware styling.

Staff-Only Content Management

Comprehensive staff-only content management system ensuring Ace Strategies staff-only materials remain separate from IAA member content. Articles are automatically tagged as staff-only and excluded from public collections in production builds.

Enhanced Filtering System

Sophisticated client-side filtering mechanism with improved search capabilities, category filtering, and status-based organization. The system now supports tag-based filtering and enhanced user experience with better empty state handling.

Platform Documentation

Technical documentation covering the complete platform architecture, including technology stack, authentication model, deployment procedures, and operational guidelines for staff members.

Section sources

  • [src/staff.njk:18-167](file://src/staff.njk#L18-L167)
  • [src/staff-knowledge.njk:22-192](file://src/staff-knowledge.njk#L22-L192)
  • [src/staff-knowledge-graph.njk:8-55](file://src/staff-knowledge-graph.njk#L8-L55)
  • [src/content/knowledge/briefing-note-playbook.md:1-97](file://src/content/knowledge/briefing-note-playbook.md#L1-L97)
  • [src/content/knowledge/media-enquiry-protocol.md:1-108](file://src/content/knowledge/media-enquiry-protocol.md#L1-L108)
  • [src/content/knowledge/staff-onboarding.md:1-109](file://src/content/knowledge/staff-onboarding.md#L1-L109)

Architecture Overview

The enhanced Staff Portal follows a distributed architecture pattern combining static site generation with serverless authentication and advanced content management:

sequenceDiagram
participant User as "Staff Member"
participant Portal as "Staff Portal"
participant Worker as "Cloudflare Worker"
participant CMS as "Sveltia CMS"
participant KV as "KV Storage"
participant Assets as "Static Assets"
User->>Portal : Access /staff/
Portal->>Worker : Request validation
Worker->>Worker : Verify session cookie
alt Valid session
Worker->>Assets : Serve protected content
Assets-->>User : Staff portal pages
else Invalid session
Worker->>User : Redirect to login
User->>Worker : Submit email
Worker->>KV : Store temporary token
Worker->>User : Send magic link email
User->>Worker : Click verification link
Worker->>KV : Validate token
Worker->>User : Set session cookie
Worker->>Assets : Redirect to portal
end
User->>CMS : Access /admin/
CMS->>Worker : OAuth authentication
Worker->>Worker : GitHub OAuth flow
Worker->>User : Return CMS access token
User->>CMS : Edit content

Diagram sources

  • [worker.js:83-93](file://worker.js#L83-L93)
  • [worker.js:99-177](file://worker.js#L99-L177)
  • [worker.js:183-207](file://worker.js#L183-L207)
  • [src/admin/index.html:8-11](file://src/admin/index.html#L8-L11)

The enhanced architecture employs several key design patterns:

  • Magic Link Authentication: Stateless authentication using time-limited tokens stored in KV namespace
  • Static Site Generation: Content rendered at build time for optimal performance and security
  • Serverless Edge Computing: Authentication logic executed at Cloudflare's edge locations
  • Git-Based Content Management: Decoupled CMS with version-controlled content storage
  • Theme-Aware Styling: Comprehensive CSS custom property system supporting light and dark themes
  • Advanced Content Segregation: Automatic staff-only content filtering and audience targeting

Section sources

  • [worker.js:12-20](file://worker.js#L12-L20)
  • [worker.js:340-358](file://worker.js#L340-L358)
  • [src/admin/config.yml:1-5](file://src/admin/config.yml#L1-L5)

Detailed Component Analysis

Staff Portal Dashboard Implementation

The dashboard template orchestrates multiple data sources and presentation layers with enhanced statistics and quick access features:

flowchart TD
Start([Load Staff Portal]) --> FetchData["Fetch Collections<br/>- staffKnowledge<br/>- staffKnowledgeByCategory"]
FetchData --> GroupArticles["Group by Status<br/>- Drafts<br/>- In Review<br/>- Published"]
GroupArticles --> RenderStats["Render Enhanced Stats<br/>- Total Articles<br/>- Status Counts<br/>- Staff-Only Count"]
RenderStats --> RenderTiles["Render Quick Access Tiles<br/>- CMS<br/>- Knowledge Base<br/>- Knowledge Graph<br/>- Guides<br/>- Platform Docs"]
RenderTiles --> RenderLists["Render Status Lists<br/>- Recent Drafts<br/>- In Review Articles<br/>- Recently Published"]
RenderLists --> End([Complete Page Load])

Diagram sources

  • [src/staff.njk:8-16](file://src/staff.njk#L8-L16)
  • [src/staff.njk:110-126](file://src/staff.njk#L110-L126)
  • [src/staff.njk:129-145](file://src/staff.njk#L129-L145)
  • [src/staff.njk:147-164](file://src/staff.njk#L147-L164)

The enhanced dashboard implements responsive grid layouts, status-based color coding, and interactive hover states. Each tile provides direct navigation to specific portal features, while the status lists offer quick access to content requiring attention.

Section sources

  • [src/staff.njk:18-167](file://src/staff.njk#L18-L167)
  • [src/assets/css/modules/45-staff-portal.css:54-695](file://src/assets/css/modules/45-staff-portal.css#L54-L695)

Enhanced Knowledge Base Interface

The knowledge base now features three new staff-only articles integrated seamlessly with the existing infrastructure:

New Staff Knowledge Articles

  • Briefing Note Playbook: Comprehensive guide for producing briefing notes with research standards, turnaround expectations, and review checklists
  • Media Enquiry Protocol: Fast-path protocol for triaging, logging, drafting, and clearing media responses
  • Staff Onboarding: Two-week onboarding guide for new Ace Strategies employees

Enhanced Article Structure

Each article includes:

  • Staff-only audience designation
  • Related article linking system
  • Comprehensive tagging and categorization
  • Status tracking (draft, review, published, archived)
  • Last updated timestamps

Section sources

  • [src/content/knowledge/briefing-note-playbook.md:1-97](file://src/content/knowledge/briefing-note-playbook.md#L1-L97)
  • [src/content/knowledge/media-enquiry-protocol.md:1-108](file://src/content/knowledge/media-enquiry-protocol.md#L1-L108)
  • [src/content/knowledge/staff-onboarding.md:1-109](file://src/content/knowledge/staff-onboarding.md#L1-L109)

Enhanced Knowledge Base Infrastructure

Staff-Only Content Management

The knowledge base infrastructure has been enhanced with comprehensive staff-only content management:

classDiagram
class StaffKnowledgeBase {
+Collection staffKnowledge
+Collection staffKnowledgeByCategory
+Collection staffKnowledgeByStatus
+Collection staffKnowledgeByAudience
+filterByAudience(audience) Article[]
+filterByStatus(status) Article[]
+filterByCategory(category) Article[]
+generateGraphData() GraphData[]
}
class Article {
+string title
+string audience
+string status
+string category
+Array related_articles
+Array tags_list
+Date last_updated
+boolean isPublished
+boolean isDraft
}
class StaffOnlyArticle {
+string audience = "staff"
+boolean isPublished
+boolean isDraft
+renderStaffOnlyBadge() HTMLElement
}
class PublicArticle {
+string audience = "members"|"both"
+renderPublicBadge() HTMLElement
}
StaffKnowledgeBase --> Article : manages
Article --> StaffOnlyArticle : extends
Article --> PublicArticle : extends

Diagram sources

  • [src/content/knowledge/knowledge.11tydata.js:1-47](file://src/content/knowledge/knowledge.11tydata.js#L1-L47)
  • [src/staff-knowledge.njk:8-20](file://src/staff-knowledge.njk#L8-L20)

The enhanced system ensures:

  • Automatic staff-only article exclusion from public collections
  • Audience-based content filtering and display
  • Separate knowledge bases for Ace Strategies and IAA members
  • Enhanced security through proper content segregation

Section sources

  • [src/content/knowledge/knowledge.11tydata.js:6-10](file://src/content/knowledge/knowledge.11tydata.js#L6-L10)
  • [src/content/knowledge/knowledge.11tydata.js:28-34](file://src/content/knowledge/knowledge.11tydata.js#L28-L34)

Comprehensive Article Management

The enhanced article management system supports:

  • Status Tracking: Automatic status-based collection inclusion/exclusion
  • Audience Segmentation: Staff-only vs. public content distinction
  • Category Organization: Hierarchical content categorization
  • Tag System: Flexible tagging for enhanced discoverability
  • Related Articles: Intelligent cross-linking between related content
  • Content Types: Differentiated content formats (guides, playbooks, onboarding)

Section sources

  • [src/_includes/layouts/staff-knowledge-article.njk:12-110](file://src/_includes/layouts/staff-knowledge-article.njk#L12-L110)
  • [src/staff-knowledge.njk:107-171](file://src/staff-knowledge.njk#L107-L171)

Improved Filtering System

Advanced JavaScript Modules

The filtering system has been enhanced with sophisticated JavaScript modules:

classDiagram
class KnowledgeBaseFilter {
+string searchTerm
+string categoryFilter
+string statusFilter
+string audienceFilter
+Array selectedTags
+filterKB() void
+clearFilters() void
+updateVisibility() void
+showEmptyState() void
+applyTagFilter(tag) void
+removeTagFilter(tag) void
}
class ArticleRow {
+string title
+string category
+string status
+string audience
+Array tags_list
+Date lastUpdated
+HTMLElement element
+isVisible() boolean
+toggleDisplay(show) void
}
class CategorySection {
+string categoryName
+HTMLElement element
+boolean hasVisibleRows
+updateVisibility() void
}
class TagFilter {
+string tagName
+HTMLElement element
+boolean isActive
+toggleActive() void
+applyFilter() void
}
KnowledgeBaseFilter --> ArticleRow : "manages"
KnowledgeBaseFilter --> CategorySection : "controls"
KnowledgeBaseFilter --> TagFilter : "uses"
ArticleRow --> CategorySection : "belongs to"
ArticleRow --> TagFilter : "has tags"

Diagram sources

  • [src/staff-knowledge-list.js:20-67](file://src/staff-knowledge-list.js#L20-L67)
  • [src/staff-knowledge-list.js:69-74](file://src/staff-knowledge-list.js#L69-L74)

The enhanced filtering system processes multiple criteria simultaneously:

  • Search Term: Case-insensitive substring matching against article titles
  • Category Filter: Exact category matching with parent category fallback
  • Status Filter: Direct status matching (draft, review, published, archived)
  • Audience Filter: Staff-only vs. public content filtering
  • Tag Filter: Advanced tag-based content discovery

Section sources

  • [src/staff-knowledge-list.js:1-99](file://src/staff-knowledge-list.js#L1-L99)
  • [src/staff-knowledge.njk:74-94](file://src/staff-knowledge.njk#L74-L94)

Enhanced User Experience Features

The improved filtering system includes:

  • Real-time Filtering: Instant results as users type or select filters
  • Tag-Based Discovery: Clickable tags that filter content dynamically
  • Empty State Handling: Clear messaging when no articles match filters
  • Filter Persistence: URL parameter support for sharing filtered views
  • Accessibility: Keyboard navigation and screen reader support

Section sources

  • [src/staff-knowledge-list.js:82-91](file://src/staff-knowledge-list.js#L82-L91)
  • [src/staff-knowledge.njk:181-186](file://src/staff-knowledge.njk#L181-L186)

Enhanced Knowledge Graph Visualization

Advanced D3.js Implementation

The knowledge graph visualization has been significantly enhanced with improved D3.js modules:

flowchart LR
Data[Knowledge Base Data] --> Parser[JSON Parser]
Parser --> NodeBuilder[Enhanced Node Builder]
Parser --> LinkBuilder[Improved Link Builder]
NodeBuilder --> ColorMap[Advanced Category Color Mapping]
LinkBuilder --> ForceSim[Enhanced Force Simulation]
ColorMap --> ForceSim
ForceSim --> Layout[Optimized Layout Calculation]
Layout --> Renderer[Improved SVG Renderer]
Renderer --> Interactions[Enhanced User Interactions]
Interactions --> Tooltip[Advanced Tooltip System]
Interactions --> Navigation[Improved Navigation Controls]
Interactions --> ZoomControls[Zoom and Pan Controls]

Diagram sources

  • [src/staff-knowledge-graph-data.njk:5-25](file://src/staff-knowledge-graph-data.njk#L5-L25)
  • [src/staff-knowledge-graph.js:31-209](file://src/staff-knowledge-graph.js#L31-L209)

The enhanced graph implementation features:

  • Dynamic Force Simulation: Physics-based positioning with customizable forces
  • Interactive Controls: Enhanced zoom, pan, and node dragging capabilities
  • Visual Hierarchy: Improved node sizing based on connection degree, color coding by category
  • Real-time Updates: Live filtering and enhanced tooltip interactions
  • Theme Awareness: CSS-driven theming that adapts to light/dark mode
  • Performance Optimization: Efficient rendering for large datasets

Section sources

  • [src/staff-knowledge-graph.js:1-217](file://src/assets/js/modules/staff-knowledge-graph.js#L1-L217)
  • [src/staff-knowledge-graph.njk:43-55](file://src/staff-knowledge-graph.njk#L43-L55)

Enhanced Graph Features

The improved knowledge graph includes:

  • Advanced Tooltips: Rich information display with status, category, and tags
  • Legend System: Dynamic category legend with color coding
  • Statistics Display: Real-time article and connection counts
  • Reset Controls: One-click graph reset functionality
  • Responsive Design: Adaptive sizing for different screen dimensions
  • Accessibility: Screen reader support and keyboard navigation

Section sources

  • [src/staff-knowledge-graph.js:59-81](file://src/staff-knowledge-graph.js#L59-L81)
  • [src/staff-knowledge-graph.js:171-200](file://src/staff-knowledge-graph.js#L171-L200)
  • [src/staff-knowledge-graph.njk:29-48](file://src/staff-knowledge-graph.njk#L29-L48)

Staff-Only Content Management

Comprehensive Content Segregation

The staff-only content management system ensures proper separation between Ace Strategies internal content and IAA member content:

stateDiagram-v2
[*] --> ContentCreation
ContentCreation --> StaffOnlyValidation : Article Created
StaffOnlyValidation --> AudienceCheck : Check audience field
audienceCheck --> StaffOnly : audience = "staff"
audienceCheck --> PublicContent : audience = "members"|"both"
StaffOnly --> CollectionFilter : Filter collections
PublicContent --> CollectionFilter : Include in collections
CollectionFilter --> ProductionBuild : Build for production
CollectionFilter --> PreviewBuild : Build for preview
ProductionBuild --> PublishedArticles : Only published/review
PreviewBuild --> AllArticles : Include drafts
PublishedArticles --> [*]
AllArticles --> [*]

Diagram sources

  • [src/content/knowledge/knowledge.11tydata.js:6-10](file://src/content/knowledge/knowledge.11tydata.js#L6-L10)
  • [src/content/knowledge/knowledge.11tydata.js:28-34](file://src/content/knowledge/knowledge.11tydata.js#L28-L34)

The system enforces:

  • Automatic Staff-Only Flagging: All knowledge articles default to staff-only
  • Collection Filtering: Production builds exclude non-published content
  • Separate Knowledge Bases: Distinct URLs for staff and member content
  • Security Boundaries: Proper content isolation between organizations

Section sources

  • [src/content/knowledge/knowledge.11tydata.js:6-10](file://src/content/knowledge/knowledge.11tydata.js#L6-L10)
  • [src/content/knowledge/knowledge.11tydata.js:16-34](file://src/content/knowledge/knowledge.11tydata.js#L16-L34)

Enhanced Article Layout System

The staff knowledge article layout system provides comprehensive styling and functionality:

classDiagram
class StaffKnowledgeLayout {
+layout base.njk
+seoMetaTags SEO
+breadcrumb Navigation
+statusBadges Display
+tableOfContents Generation
+relatedArticles Display
+readingTime Calculation
+difficultyLevels Display
}
class ArticleContent {
+markdownContent Processing
+wikilinkSupport Processing
+calloutStyles Rendering
+proseFormatting Styling
+codeBlockSyntax Highlighting
}
class ThemeAwareComponents {
+darkTheme Support
+lightTheme Support
+cssCustomProperties Theming
+responsiveDesign Adaption
}
StaffKnowledgeLayout --> ArticleContent : renders
StaffKnowledgeLayout --> ThemeAwareComponents : uses
ArticleContent --> ThemeAwareComponents : styled by

Diagram sources

  • [src/_includes/layouts/staff-knowledge-article.njk:12-110](file://src/_includes/layouts/staff-knowledge-article.njk#L12-L110)

The enhanced layout system includes:

  • SEO Optimization: Automatic meta description generation
  • Reading Time Calculation: Accurate reading time estimates
  • Difficulty Indicators: Visual difficulty level indicators
  • Table of Contents: Automatic TOC generation from headings
  • Related Articles: Intelligent cross-linking system
  • Theme Integration: Seamless integration with global theme system

Section sources

  • [src/_includes/layouts/staff-knowledge-article.njk:12-110](file://src/_includes/layouts/staff-knowledge-article.njk#L12-L110)

Dependency Analysis

The enhanced Staff Portal implementation demonstrates clear separation of concerns with well-defined dependencies:

graph TB
subgraph "Enhanced Frontend Dependencies"
CSS["Staff Portal CSS (45-staff-portal.css)"]
SKS["Staff Knowledge Scope CSS (47-staff-knowledge-scope.css)"]
JS["D3.js (knowledge-graph)"]
HTML["Nunjucks Templates"]
TOC["Table of Contents JS"]
LIST["List Filter JS"]
GRAPH["Graph Visualization JS"]
end
subgraph "Backend Dependencies"
Worker["Cloudflare Worker (worker.js)"]
KV["KV Namespaces"]
API["External APIs"]
end
subgraph "Enhanced Content Dependencies"
Eleventy["Eleventy (knowledge.11tydata.js)"]
Data["_data/site.json"]
Layout["_includes/layouts/knowledge.njk"]
StaffLayout["_includes/layouts/staff-knowledge-article.njk"]
end
subgraph "Build Dependencies"
Package["package.json"]
Scripts["NPM Scripts"]
end
CSS --> HTML
SKS --> HTML
JS --> HTML
TOC --> HTML
LIST --> HTML
GRAPH --> HTML
HTML --> Worker
Worker --> KV
Worker --> API
Eleventy --> Layout
Eleventy --> StaffLayout
Eleventy --> Data
Package --> Scripts
Package --> Eleventy
Package --> Worker

Diagram sources

  • [src/assets/css/modules/45-staff-portal.css:1-695](file://src/assets/css/modules/45-staff-portal.css#L1-L695)
  • [src/assets/css/modules/47-staff-knowledge-scope.css:1-612](file://src/assets/css/modules/47-staff-knowledge-scope.css#L1-L612)
  • [worker.js:68-77](file://worker.js#L68-L77)
  • [src/content/knowledge/knowledge.11tydata.js:1-47](file://src/content/knowledge/knowledge.11tydata.js#L1-L47)
  • [package.json:5-12](file://package.json#L5-L12)

The enhanced dependency structure reveals:

  • Modular CSS Architecture: Separate styling modules for different contexts
  • Advanced JavaScript Modules: Specialized modules for different functionality
  • Enhanced Content Agnostic: Templates work with various content sources through collections
  • Improved Build System Integration: NPM scripts orchestrate the entire enhanced deployment pipeline

Section sources

  • [package.json:1-32](file://package.json#L1-L32)
  • [src/assets/css/modules/45-staff-portal.css:1-695](file://src/assets/css/modules/45-staff-portal.css#L1-L695)
  • [src/assets/css/modules/47-staff-knowledge-scope.css:1-612](file://src/assets/css/modules/47-staff-knowledge-scope.css#L1-L612)
  • [worker.js:339-358](file://worker.js#L339-L358)

Performance Considerations

The enhanced Staff Portal implementation incorporates several performance optimization strategies:

Static Generation Benefits

  • Zero Runtime Costs: All content rendered at build time eliminates server-side processing
  • Edge Delivery: Cloudflare's global network caches content for optimal delivery
  • Reduced Complexity: Stateless architecture simplifies scaling and maintenance

Enhanced Authentication Efficiency

  • Edge Computing: Authentication logic executes at network edge closest to users
  • KV Namespace Optimization: Efficient key-value storage for session and token management
  • Rate Limiting: Built-in protection against abuse without impacting legitimate users

Advanced Frontend Performance

  • Modular CSS Architecture: Component-based styling reduces bundle sizes and improves caching
  • Lazy Loading: Interactive elements load only when needed (D3.js graph, table of contents)
  • Responsive Design: Mobile-first approach ensures optimal performance across devices
  • Theme-Aware Optimization: CSS custom properties enable efficient theme switching

Enhanced Content Delivery

  • CDN Integration: Static assets served through Cloudflare's CDN infrastructure
  • Compression: Automatic compression of assets for reduced bandwidth usage
  • Caching Strategy: Intelligent caching headers balance freshness with performance
  • Graph Data Optimization: Efficient JSON data generation for knowledge graph

Improved Filtering Performance

  • Client-Side Optimization: Efficient JavaScript filtering with DOM manipulation
  • Memory Management: Proper cleanup of event listeners and DOM references
  • Accessibility Optimization: Screen reader and keyboard navigation support

Troubleshooting Guide

Authentication Issues

Common authentication problems and solutions:

Problem: Users unable to receive magic link emails

  • Cause: Missing or misconfigured Resend API key
  • Solution: Verify RESEND_API_KEY secret is properly configured in Cloudflare Workers

Problem: Session cookies not persisting

  • Cause: Browser privacy settings blocking third-party cookies
  • Solution: Ensure browser allows cookies for the domain and check SameSite cookie settings

Problem: Rate limit errors during login attempts

  • Cause: Excessive login attempts from single IP address
  • Solution: Wait for rate limit window to expire (60 seconds) or reduce login frequency

Enhanced Content Management Problems

Problem: New staff-only articles not appearing in search

  • Cause: Articles in draft status excluded from production collections
  • Solution: Change article status to "published" or "review" for visibility

Problem: Knowledge graph not displaying new articles

  • Cause: Graph data cache not updated
  • Solution: Clear browser cache or refresh the graph page to regenerate data

Problem: Related articles not linking correctly

  • Cause: Mismatched title formatting in related_articles field
  • Solution: Ensure related article titles match exactly with target article titles

Advanced Filtering Issues

Problem: Tag-based filtering not working

  • Cause: JavaScript module not loading or DOM not ready
  • Solution: Check browser console for JavaScript errors and ensure proper module loading

Problem: Filter persistence not working

  • Cause: URL parameter handling issues
  • Solution: Verify URL encoding and parameter parsing in the filtering script

Performance Issues

Problem: Slow page load times

  • Cause: Large image assets or excessive JavaScript
  • Solution: Optimize images using the provided build process and minimize external dependencies

Problem: Knowledge graph rendering delays

  • Cause: Large number of articles affecting D3.js performance
  • Solution: Consider pagination or filtering to reduce dataset size

Problem: Theme switching issues

  • Cause: CSS custom property conflicts or JavaScript initialization errors
  • Solution: Check browser developer tools for CSS variable conflicts and verify theme toggle functionality

Section sources

  • [worker.js:72-77](file://worker.js#L72-L77)
  • [src/content/knowledge/knowledge.11tydata.js:23-29](file://src/content/knowledge/knowledge.11tydata.js#L23-L29)
  • [src/staff-knowledge-list.js:82-91](file://src/staff-knowledge-list.js#L82-L91)

Conclusion

The enhanced Staff Portal Implementation represents a sophisticated evolution of the original system, incorporating modern web technologies and comprehensive feature enhancements. The implementation successfully balances security, usability, and performance while providing robust staff-only content management and advanced knowledge discovery capabilities.

Key achievements include:

  • Enhanced Staff-Only Content Management: Comprehensive segregation of Ace Strategies internal content from IAA member materials
  • Advanced Knowledge Base Infrastructure: Integration of three new staff-only articles with improved filtering and visualization
  • Improved User Experience: Sophisticated filtering system with tag-based discovery and enhanced graph visualization
  • Robust Authentication: Secure magic-link system with comprehensive security measures
  • Scalable Architecture: Serverless design enabling easy scaling and maintenance
  • Developer Experience: Comprehensive platform documentation and development tools

The modular approach to styling, content management, and authentication creates a maintainable foundation for ongoing development. The integration of D3.js for enhanced knowledge graph visualization demonstrates innovative approaches to content discovery and relationship mapping.

The enhanced filtering system with tag-based discovery and improved user experience provides staff members with powerful tools for finding relevant information quickly. The comprehensive staff-only content management ensures proper separation between internal and external materials while maintaining accessibility for authorized users.

Future enhancement opportunities include expanding the knowledge graph visualization capabilities, implementing advanced analytics for content usage, and enhancing the CMS with collaborative editing features. The current architecture provides excellent foundation for these improvements while maintaining backward compatibility and system stability.

The integration of three new staff-only articles (Briefing Note Playbook, Media Enquiry Protocol, and Staff Onboarding) significantly enhances the portal's utility for Ace Strategies employees, providing comprehensive guidance for daily operations and professional development. The enhanced filtering and graph visualization systems make these resources easily discoverable and interconnected, creating a more cohesive knowledge management experience.